package SSF.OS.Socket;

/*
 * Original author: Jim Cowie, Hongbo Liu
 * Revisions: Andy Ogielski
 */



public interface socketAPI  {

// Nonblocking calls.  ----------------------------------------

  /** 
   * Bind the local IP address and port number to the socket.
   * @param local_ip local IP address 
   * @param local_port local port number
   */ 
  public void bind(int local_ip, int local_port);

  /**
   * Set up the socket to accept incoming connection requests (TCP)
   * or incoming datagrams (UDP) on the port bound to the socket.
   * Creates an instance of tcpSession or udpSession in passive open state
   * and binds it to the socket.
   * @param queue_limit For tcpSocket, specifies the maximum number of connection
   * requests pending accept. Ignored by udpSocket.
   */ 
  public void listen(int queue_limit);

// Blocking calls.     ----------------------------------------

  /**
   * For TCP, active open a connection to a remote host (blocking). <P>
   * For UDP, set up a UDP session for writing (non-blocking).
   * @param remote_ip remote IP address
   * @param remote_port remote port number
   * @param caller user-defined Continuation specifying the actions
   *        to be taken when a connection is either successfully
   *        established or an error is signalled.
   */
  public void connect(int remote_ip, int remote_port, Continuation caller)
    throws ProtocolException;

  /**
   * For TCP, accept an established connection (after three-way handshake)
   * from the pending connection request queue. Blocking if there are
   * no pending established connection requests. <P>
   * Do not use with UDP sockets.
   * @param new_socket one-element array that will contain the new connected
   *                   socket when Continuation returns successfully.
   * @param caller user-defined Continuation specifying the actions
   *        to be taken when a connection is either successfully
   *        accepted or an error is signalled.
   */
  public void accept(socketAPI[] new_socket, Continuation caller)
    throws ProtocolException;

  /**
   * Write a concrete data object to the socket.
   * @param obj user-defined array whose first element obj[0] will be sent
   * @param nbytes nominal size (in bytes) of the data object that defines
   *        the transmitted payload size
   * @param caller user-defined Continuation specifying the actions
   *        to be taken when either nbytes of (virtual) data is successfully
   *        written or an error is signalled.
   */
  public void write(Object[] obj, int nbytes, Continuation caller);

  /**
   * Write data from a byte array to the socket.
   * @param obj user-defined byte array
   * @param nbytes size of data to be transmitted
   * @param caller user-defined Continuation specifying the actions
   *        to be taken when either nbytes of data is successfully
   *        written or an error is signalled.
   */
  public void write(byte[] buf, int nbytes, Continuation caller);

  /**
   * Write simulated pseudo-data to the socket.
   * @param nbytes number of bytes of pseudo-data that defines the
   *        transmitted payload size
   * @param caller user-defined Continuation specifying the actions
   *        to be taken when either nbytes of data is successfully
   *        written or an error is signalled.
   */
  public void write(int nbytes, Continuation caller);

  /** 
   * Read the data received by socket and write them into user-defined
   * byte array. Blocks until nbytes of data is received
   * or an error is signalled.
   * @param byte byte array containing the received data
   * @param nbytes expected received data size
   * @param caller user-defined Continuation specifying the actions
   *        to be taken when either all data is read successfully
   *        or an error is signalled.
   */
  public void read(byte[] buf, int nbytes,  Continuation caller);

  /** 
   * Read a data object received by the socket.
   * @param obj user-defined array whose first element obj[0] will
   * contain the data object if read is successful
   * @param nbytes expected number of received data bytes
   * @param caller user-defined Continuation specifying the actions
   *        to be taken when either all data is read successfully
   *        or an error is signalled.
   */
  public void read(Object[] obj, int nbytes,  Continuation caller);

  /** 
   * Read pseudo-data received by the socket.
   * @param nbytes expected number of bytes of received pseudo-data
   * @param caller user-defined Continuation specifying the actions
   *        to be taken when either all data is read successfully
   *        or an error is signalled.
   */
  public void read(int nbytes, Continuation caller);
  
  /**
   * Abort a connection. For TCP, will cause a RESET to be sent.
   */
  public void abort();

  /**
   * Close a connection.
   * @param caller the user defined Continuation class which defines the
   *        action should be taken when connection is either successfully
   *        closed or an error is signalled.
   */
  public void close(Continuation caller) throws ProtocolException;

} // socketAPI
